Garfield++ is an object-oriented toolkit for the detailed simulation of 
particle detectors that are based on ionisation measurement in 
gases or semiconductors.

For calculating electric fields, three techniques are currently
being offered:
\begin{itemize}
  \item
  solutions in the thin-wire limit for devices made of wires and planes;
  \item
  interfaces with finite element programs, 
  which can compute approximate fields in nearly arbitrary 
  two- and three-dimensional configurations 
  with dielectrics and conductors;
  \item
  an interface with the Synopsys Sentaurus device simulation program
  \cite{Synopsys}.
\end{itemize}

In the future, an interface to the neBEM field solver 
\cite{Mukhopadhyay2007,Mukhopadhyay2006} 
(which already exists for Garfield \cite{GarfieldFortran}), 
should be made available.

For calculating the transport properties of electrons in gas 
mixtures, an interface to the ``Magboltz'' program 
\cite{BiagiMagboltz,Biagi1999} is available. 

The ionization pattern produced along the 
track of relativistic charged particles can be simulated using 
the program ``Heed'' \cite{Smirnov2005}.
For simulating the ionization produced by low-energy ions, 
an interface for importing results calculated using the 
SRIM software package \cite{Ziegler1985} 
is available.

The present document aims to give an overview of Garfield++, 
but does not provide an exhaustive 
description of all classes and functions.
A number of examples and code snippets are included 
which may serve as a basis for the user's own programs. 
Further examples and information can be found on the webpage 
%\href{http://garfieldpp.web.cern.ch/garfieldpp/}{http://cern.ch/garfieldpp}.
\url{http://garfieldpp.web.cern.ch/garfieldpp/}.
If you have questions, doubts, comments \textit{etc.} about the code 
or this manual, please don't hesitate to contact the authors.
 
\section{Class Structure}

An overview of the different types of classes is given in 
Fig.~\ref{Fig:OverviewClasses}. 
Two main categories can be distinguished: 
classes for describing the detector 
(material properties, geometry, fields), 
and transport classes which deal with tracing particles 
through the device. 
The two class types are linked by the class \texttt{Sensor}.

\begin{figure}
  \centering 
  {
  \linespread{0.9} 
  \begin{tikzpicture}[scale=2, node distance = 4em, 
                      auto, label distance = 1em]

    \node (medium) [block,
                    label=left:{\parbox{10em}{
                    \footnotesize material properties 
                    \begin{itemize} 
                      \item gas \(\rightarrow\) Magboltz 
                      \item silicon 
                    \end{itemize}}}]  {\small Medium};
    \node (dummy)  [right of=medium,
                    label=above:{\small Detector Description}] {};
    \node (geo)    [block,right of = dummy]  {\small Geometry};
    \node (comp1)  [block, below of = dummy, 
                    xshift = 1em, yshift = -1em]     {};
    \node (comp2)  [block, below of = dummy,
                    xshift =.5em,yshift=-.5em]   {};
    \node (comp)   [block, below of = dummy,
                    label=left:{\parbox{8em}{
                    \footnotesize \vspace{2em} 
                    field calculation 
                    \begin{itemize} 
                      \item analytic 
                      \item field maps 
                      \item \textcolor{DarkGrey}{neBEM} 
                    \end{itemize}}}]  {\footnotesize Component};
    \node (sensor) [block, below of = comp]  {\small Sensor};
    \node (dummy1) [below of = sensor,
                    label=below:{\small Transport}] {};
    \node (aval)   [drift, right of=dummy1,label=right:{\parbox{8em}{\footnotesize charge transport \begin{itemize} \item microscopic \item MC \item RKF \end{itemize}}}]        {\small Drift};
    \node (track)  [drift, left of=dummy1,label=left:{\parbox{8em}{\footnotesize primary ionization \begin{itemize} \item Heed \item SRIM \end{itemize}}}]      {\small Track}; 
    \path [line]   (medium) -- (comp);
    \path [line]   (geo)    -- (comp);
    \path [line]   (comp)   -- (sensor);
    \path [line,dashed]  (sensor) -- (track);
    \path [line,dashed]  (sensor) -- (aval);
  \end{tikzpicture}
  }
  \caption{Overview of the main classes in 
           Garfield\kern-0.05em+\kern-0.05em+ and their interplay.}
  \label{Fig:OverviewClasses}
\end{figure}

The individual classes are explained in detail in the following chapters. 

Readers familiar with the structure 
of (Fortran) Garfield \cite{GarfieldFortran} will recognize a 
rough correspondence between 
the above classes and the sections of Garfield. 
\texttt{Medium} classes, for instance, can be regarded as the counterpart 
of the \texttt{\&GAS} section; 
\texttt{Component} classes are similar in 
scope to the \texttt{\&CELL} section.  
 
Garfield\kern-0.05em+\kern-0.05em+ also includes a number of classes for visualization purposes, 
\textit{e.\,g.} for plotting drift lines, making a contour plot of the electrostatic 
potential or inspecting the layout of the detector.   
These classes rely extensively on the graphics classes of the 
ROOT framework \cite{ROOT}.

